#!/usr/bin/perl -c

package PIPL::System::Env;
use 5.006;
our $VERSION = '0.01';

=head1 NAME

PIPL::System::Env - Singleton for wrapping %ENV variable

=head1 SYNOPSIS

  use PIPL::System::Env;
  $env = PIPL::System::Env->instance;
  $path = $env->{PATH};

  $home = $PIPL::System::Env::Self->{HOME};

=head1 DESCRIPTION

This singleton class gives an access to Perl's environment variables through
the object reference.  It can be more handy than accessing pure B<%ENV>
variable if unit tests are used or some wrapping for B<%ENV> is needed.

The environment variable is accessable by instance variable (B<new> or
B<instance> constructor) or by static variable B<$PIPL::System::Env::Self>.

=cut


use strict;

use base 'PIPL::Class::Singleton';


# Private constructor used by singleton constructor
sub new {
    my $class = shift;
    $class = ref $class if ref $class;
    bless \%ENV => $class;
}


# Initialize singleton instance at start
__PACKAGE__->instance;

1;


=head1 BASE CLASSES

=over 2

=item *

L<PIPL::Class::Singleton>

=back

=head1 FIELDS

=over

=item I<variable> (rw)

The environment variable.

  $v = $PIPL::System::Env::Self->{PATH};

=back

=head1 CONSTRUCTORS

=over

=item new

Create new object.

  $obj = new PIPL::System::Env;
  $path = $obj->{PATH};

=item instance

Return existing instance of class or create new object.

  $obj = instance PIPL::System::Env;
  $path = $obj->{PATH};

=back

=head1 STATIC OBJECT INSTANCE

The class provides static object instance:

  use PIPL::System::Env;
  
  print $PIPL::System::Env::Self->{PATH};

=head1 SEE ALSO

L<PIPL::Class::Singleton>.

=head1 AUTHORS

Piotr Roszatycki E<lt>dexter@debian.orgE<gt>

=head1 LICENSE

Copyright 2007 by Piotr Roszatycki E<lt>dexter@debian.orgE<gt>.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

See L<http://www.perl.com/perl/misc/Artistic.html>
